25장 ccusage로 사용량 보기 (입문판)

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호)

이 장에서 딱 4가지만

1. 클로드 코드는 내가 토큰을 얼마나 썼는지 안 알려준다 — 그래서 ccusage가 필요하다.
2. ccusage는 설치 없이 bunx로 바로 실행한다.
3. daily / monthly / session / blocks 네 가지로 "언제·어디에·얼마나" 썼는지 본다.
4. ccusage를 MCP 서버로 붙이면, 클로드 코드한테 말로 "오늘 얼마 썼어?" 물어볼 수 있다.

이 장에 나오는 도구 이름 약속. ccusage, bun, bunx, MCP는 모두 공식 명칭 그대로 쓴다. ccusage는 서드파티(다른 사람이 만든) 오픈소스 도구다. 그래서 설치법이나 화면은 바뀔 수 있다 — 정확한 최신 설치법은 항상 각 도구의 공식 저장소에서 확인하자. (원서 작성 시점 기준 소개다.)

이 장에서 나오는 구체적인 요금 숫자나 토큰 수, 모델 이름은 원서/노트에 적힌 예시 값이다. 실제 최신 값은 공식 문서에서 확인하자.

학습 목표

이 장을 끝내면 이런 걸 할 수 있다.

• 왜 ccusage 같은 도구가 필요한지 설명한다.
• bun을 설치하고 bunx로 ccusage를 실행하는 과정을 따라 한다.
• daily / monthly / session / blocks 네 명령을 구분한다.
• 기간 필터(--since / --until)와 라이브 모니터링을 따라 한다.
• ccusage를 MCP 서버로 붙이는 방법을 따라 한다.

25-1 ccusage가 왜 필요할까

이런 적 있죠?

열심히 코딩을 시키고 있는데, 클로드 코드가 갑자기 멈춘다.

"5시간 후에 다시 사용할 수 있어요."

어... 내가 그렇게 많이 썼나? 얼마나 썼길래 막힌 거지? 방금까지 잘 되던 게 갑자기 멈추니 당황스럽다.

문제는 이거다. 클로드 코드는 평소에 "지금 얼마나 썼는지"를 화면에 안 보여준다. 그래서 한도에 걸리기 전까지는 내가 얼마나 썼는지 알 방법이 없다.

이걸 해결해주는 게 바로 ccusage다.

용어: ccusage란 "내가 클로드 코드를 얼마나 썼는지" 숫자로 보여주는 도구다. 핸드폰의 데이터 사용량 확인 앱이라고 생각하면 된다.

핸드폰 데이터 잔량 앱이랑 똑같다

핸드폰 데이터를 쓰다 보면 통신사 앱을 켠다. "이번 달 얼마나 썼지? 얼마 남았지?" 미리 확인하면 데이터가 다 떨어지기 전에 아껴 쓸 수 있다.

ccusage가 딱 그 역할이다. 클로드 코드의 "데이터 잔량"을 보여준다.

용어: 토큰(token)이란 AI가 글자를 세는 단위다. 통신요금의 "데이터 1MB"처럼, AI는 "토큰"으로 사용량을 센다. 입력 토큰(내가 보낸 글)과 출력 토큰(AI가 답한 글)으로 나뉜다.

클로드 코드만 쓰면 뭐가 답답할까

ccusage 없이 클로드 코드만 쓰면 이런 게 안 보인다.

• 토큰을 얼마나 썼는지 안 보인다.
• 지금 5시간 블록 중 어디쯤인지 안 보인다.
• 갑자기 "5시간 후에 사용 가능" 메시지가 뜬다.
• 어떤 모델을 얼마나 썼는지 모른다.

용어: 5시간 블록이란 클로드 코드가 사용량을 관리하는 시간 단위다. 5시간마다 한 칸씩 새로 채워지는 도시락 칸이라고 생각하면 된다. 한 칸을 다 쓰면 다음 칸이 열릴 때까지 기다린다.

ccusage를 깔면 이런 게 보인다.

• 날짜별·월별 토큰 사용량과 비용
• 프로젝트(세션)별·5시간 블록별 상세 분석
• 실시간으로 남은 시간과 토큰 예측
• 모델별 사용량 구분 (예: Sonnet 얼마, Opus 얼마)

미니 시나리오

잘못된 흐름. "왜 막혔지? 모르겠다. 그냥 5시간 기다리자." → 작업이 멈추고, 다음에도 똑같이 또 막힌다.

올바른 흐름. "ccusage로 확인해보니 오늘 Opus를 많이 썼네. 내일은 간단한 일은 Sonnet으로 돌려야겠다." → 원인을 알고 대비할 수 있다.

짚고 가기

• 클로드 코드는 평소에 토큰 사용량을 화면에 안 보여준다.
• 요금이 걱정되는 사용자일수록 사용량 확인이 중요하다.
• ccusage는 오픈소스 도구다. 아직 초기이지만 충분히 쓸 만하다.

25-2 ccusage 설치하기

이런 적 있죠?

새 도구를 쓰려고 보니 "설치하세요"라는 말부터 막막하다. 다운로드 받고, 압축 풀고, 경로 설정하고... 복잡할 것 같다.

그런데 ccusage는 의외로 간단하다. "앱을 깔지 않고 바로 실행"하는 방식이라서 그렇다.

그러려면 먼저 bun이라는 걸 깔아야 한다.

용어: bun이란 자바스크립트로 만든 도구를 빠르게 실행해주는 프로그램이다. ccusage도 그런 도구라서, ccusage를 돌리려면 bun이 먼저 있어야 한다.

용어: bunx란 bun에 딸려오는 "설치 없이 바로 실행" 버튼이다. 도구를 내 컴퓨터에 깔지 않고도 바로 돌려준다.

앱스토어에서 앱 받기랑 비슷하다

bun은 일종의 앱스토어다. bunx는 그 안의 "설치 안 하고 바로 실행" 버튼이다.

앱스토어(bun)를 먼저 깔고, 그 안에서 ccusage를 바로 실행(bunx)하면 끝이다.

1단계 — bun 설치 (OS마다 다름)

먼저 bun을 깐다. macOS와 Windows는 명령이 다르니, 내 컴퓨터에 맞는 걸 쓰자.

macOS는 터미널에서 실행한다.

curl -fsSL https://bun.com/install | bash

Windows는 PowerShell에서 실행한다.

powershell -c "irm bun.sh/install.ps1|iex"

한 걸음 더 ▸ 위 명령이 어렵게 보여도 괜찮다. 그냥 복사해서 붙여 넣으면 된다. macOS는 curl로, Windows는 PowerShell로 인터넷에서 설치 스크립트를 받아 자동으로 깐다는 뜻이다. 설치법은 바뀔 수 있으니, 안 되면 bun 공식 문서(https://bun.sh/docs)에서 최신 설치법을 확인하자.

2단계 — 설치가 됐는지 확인

설치가 잘 됐는지 확인해보자.

bunx --help

이렇게 도움말이 나오면 성공이다.

Usage: bunx [flags] <package>...

3단계 — ccusage 실행

이제 ccusage를 실행할 수 있다. 설치는 따로 안 한다. bunx가 알아서 받아서 실행해준다.

bunx ccusage daily

이 한 줄이면 끝이다. ccusage를 내 컴퓨터에 깔지 않았는데도 바로 돈다. 게다가 실행할 때마다 항상 최신 버전으로 돈다.

잘못된 예 vs 올바른 예

잘못된 예. "ccusage 설치 파일이 어디 있지? 다운로드 페이지를 찾자." → 그런 거 없다. ccusage는 따로 설치하지 않는다.

올바른 예. "bun만 깔면, bunx ccusage로 바로 실행하면 되는구나." → 맞다. bun이 깔려 있으면 ccusage는 바로 실행된다.

짚고 가기

• bun은 ccusage를 돌리는 데 필요한 기반 도구다.
• bunx는 도구를 깔지 않고 바로 실행하는 명령이다.
• macOS와 Windows는 bun 설치 명령이 다르다.
• bunx --help가 정상으로 나오면 설치 성공이다.

25-3 daily — 날짜별로 얼마 썼나 보기

이런 적 있죠?

이번 주에 클로드 코드를 많이 쓴 것 같긴 한데, 정확히 어느 날 많이 썼는지 모르겠다. 가계부를 안 쓰면 "이번 달 돈 어디로 갔지?" 하는 것과 똑같다.

daily 명령이 그 가계부 역할을 한다.

가계부 일별 지출 내역이랑 똑같다

매일 얼마 썼는지 적는 가계부를 떠올리자. "오늘은 점심에 8천 원, 어제는 택시에 2만 원."

daily는 AI 사용 가계부다. "오늘은 Sonnet에 12달러, 어제는 Opus에 43달러." 날짜별로 어떤 모델에 얼마 썼는지 정리해준다.

실제로 해보기

bunx ccusage daily

이렇게 날짜별 표가 나온다.

Date       Models           Input     Output    Cost (USD)
2025-07-20 - sonnet-4       4,419     108,474   $12.37
2025-07-21 - sonnet-4       40,397    234,335   $36.64
2025-07-22 - opus-4         18,395    168,396   $43.82
             - sonnet-4
Total                       982,901   14,984,662 $3807.68

(위 숫자는 원서/노트의 예시 값이다. 내 화면에는 내 사용량이 나온다.)

표를 어떻게 읽나

위 예시에서 7월 22일을 보자. 그날은 모델이 두 줄이다 (opus-4, sonnet-4). 하루에 두 모델을 다 썼기 때문이다. 이렇게 하루에 여러 모델을 쓰면 모델별로 나눠서 보여준다.

잘못된 예 vs 올바른 예

잘못된 예. "맨 아래 Total $3807은 오늘 하루 쓴 돈인가?" → 아니다. Total은 전체 기간을 다 더한 누적 합계다.

올바른 예. "각 날짜 줄이 그날 쓴 비용이고, 맨 밑 Total은 전부 합친 거구나." → 맞다.

짚고 가기

• daily는 날짜별 토큰 사용량과 예상 비용을 보여준다.
• 하루에 여러 모델을 썼으면 모델별로 나눠서 보여준다.
• 맨 아래 Total은 전체 기간의 누적 합계다.

25-4 monthly — 달별로 얼마 썼나 보기

이런 적 있죠?

매일 보는 것도 좋지만, "이번 달 다 합치면 얼마지?"가 궁금할 때가 있다. 지난달보다 이번 달에 많이 썼나, 줄었나도 보고 싶다.

그럴 땐 monthly다.

월별 카드 명세서랑 똑같다

매달 날아오는 카드 명세서를 떠올리자. "6월에 108만 원, 7월에 270만 원."

monthly는 AI 사용의 월별 명세서다. "6월에 1,084달러, 7월에 2,722달러." 달 단위로 묶어서 보여주니 장기 흐름이 한눈에 들어온다.

실제로 해보기

bunx ccusage monthly

이렇게 달별 표가 나온다.

Month    Models             Input     Output       Cost (USD)
2025-06  - opus-4           11,830    538,471      $1084.79
           - sonnet-4
2025-07  - opus-4           971,071   14,446,191   $2722.89
           - sonnet-4
Total                       982,901   14,984,662   $3807.68

(위 숫자는 원서/노트의 예시 값이다.)

표 읽는 법은 25-3 daily와 같다. Date가 Month(달)로 바뀐 것만 다르다.

이럴 때 이렇게

"6월보다 7월에 Opus를 훨씬 많이 썼네." → 그럼 다음 달엔 간단한 일을 Sonnet으로 돌려서 비용을 줄여보자. 이렇게 월별 추이를 보면 절약 전략을 세울 수 있다.

짚고 가기

• monthly는 달 단위로 토큰 사용량과 비용을 묶어 보여준다.
• 월별 추이를 보면 비용을 줄이는 전략을 세울 수 있다.

25-5 session — 프로젝트(작업)별로 얼마 썼나 보기

이런 적 있죠?

날짜별·월별로는 봤는데, "어떤 작업에 돈을 많이 썼지?"는 아직 모른다. A 프로젝트가 비쌌나, B 프로젝트가 비쌌나?

그걸 알려주는 게 session이다.

프로젝트별 예산 사용 현황이랑 똑같다

회사에서 프로젝트마다 예산을 따로 관리하는 걸 떠올리자. "A 프로젝트 예산 사용액, B 프로젝트 예산 사용액."

session은 그 역할이다. "A 작업에 3.78달러, B 작업에 0.76달러." 어떤 작업(세션)에 얼마 썼는지 나눠서 보여준다.

용어: 세션(session)이란 하나의 대화 흐름, 보통 하나의 프로젝트 폴더를 말한다. "이 폴더에서 한 작업 묶음"이라고 생각하면 된다.

실제로 해보기

bunx ccusage session

이렇게 세션별 표가 나온다.

Session          Models      Input    Output   Cost    Date
proj-2           - sonnet-4  46       9,463    $0.76   2025-...
improvement-18.. - sonnet-4  34,613   3,811    $0.89   2025-...
mcp-test         - sonnet-4  227      35,023   $3.78   2025-...
Desktop-asymme.. - sonnet-4  491      20,776   $3.61   2025-...

(위 숫자는 원서/노트의 예시 값이다.)

Session 칸에 폴더 이름 같은 게 보인다. 각 줄이 하나의 작업(세션)이고, 그 작업에 쓴 토큰과 비용이 나온다.

세션은 어떻게 나뉘나

규칙은 간단하다.

• 같은 프로젝트 폴더에서 한 대화 = 하나의 세션
• 워크트리로 새 폴더를 만들면 = 새로운 세션

용어: 워크트리(worktree)란 같은 프로젝트의 작업 공간을 폴더 하나 더 만들어 따로 쓰는 기능이다. 책 한 권을 복사해서 두 책상에서 따로 보는 것과 비슷하다. (워크트리 자체는 앞 장에서 다룬 내용이다.)

새 폴더가 생기면 ccusage는 그걸 다른 작업으로 보고 따로 센다. 그래서 작업마다 워크트리를 나눠 쓰면, 작업별 비용을 깔끔하게 나눠서 볼 수 있다.

이럴 때 이렇게

"새 기능 개발은 feature-A 워크트리, 버그 수정은 bugfix-B 워크트리에서 했어." → session으로 보면 feature-A와 bugfix-B의 비용이 따로 나온다. 어느 작업이 더 비쌌는지 바로 알 수 있다.

짚고 가기

• session은 작업(세션) 기준으로 사용량을 나눠 보여준다.
• 같은 폴더 대화는 한 세션, 워크트리로 만든 새 폴더는 새 세션이다.
• 어떤 작업에 토큰을 많이 썼는지 비교할 수 있다.

25-6 blocks — 5시간 블록별로 얼마 썼나 보기

이런 적 있죠?

"5시간 후에 사용 가능"이라는 메시지의 정체가 바로 이 블록이다. 지금 내가 5시간 블록 중 어디쯤 있는지, 얼마나 남았는지 보고 싶다.

그걸 보여주는 게 blocks다.

뷔페 타임 슬롯이랑 똑같다

뷔페에 시간 슬롯이 있는 걸 떠올리자. "1차 11시~2시, 2차 2시~5시." 한 슬롯 안에서 먹고, 다음 슬롯이 되면 새로 시작한다.

클로드 코드도 5시간 단위로 슬롯이 나뉜다. blocks는 각 슬롯에서 얼마나 "먹었는지"(토큰을 썼는지) 보여준다. 지금 진행 중인 슬롯이 얼마나 남았는지도 알려준다.

실제로 해보기

bunx ccusage blocks

이렇게 블록별 표가 나온다.

Time                          Status      Models      Output    Cost
07/23, 09:00 PM (1h22m)                   - sonnet-4  8,185,4.. $3.61
07/24, 03:22 AM (9h gap)      (inactive)  -           -         -
07/24, 11:00 AM (0h58m/4h2m)  ACTIVE      - sonnet-4  61,564    $0.23

(위 숫자는 원서/노트의 예시 값이다.)

상태 표시 읽는 법

위 예시 맨 아래 줄을 보자. (0h58m/4h2m)이라고 적혀 있다. 58분 동안 썼고, 4시간 2분 남았다는 뜻이다. ACTIVE는 지금 내가 쓰고 있는 블록이다.

잘못된 예 vs 올바른 예

잘못된 예. "inactive면 뭔가 고장 난 건가? 막힌 건가?" → 아니다. 그 시간대에 클로드 코드를 안 썼다는 뜻일 뿐이다.

올바른 예. "ACTIVE 줄에 4h2m 남았다고 나오네. 아직 여유 있구나." → 맞다. 지금 블록이 얼마나 남았는지 ACTIVE 줄에서 확인한다.

짚고 가기

• blocks는 5시간 블록 단위로 사용량을 보여준다.
• ACTIVE 블록에서 남은 시간을 확인할 수 있다.
• inactive는 클로드 코드를 안 쓴 빈 시간대다.

25-7 기간 골라 보기와 실시간 모니터링

이런 적 있죠?

전체 기록 말고 "7월 22일부터 23일까지"만 보고 싶을 때가 있다. 또, 지금 토큰이 줄어드는 걸 실시간으로 지켜보고 싶을 때도 있다.

기간을 고르는 건 --since / --until 플래그로, 실시간으로 보는 건 라이브 모니터링으로 한다.

용어: 플래그(flag)란 명령 뒤에 붙여서 동작을 바꾸는 추가 옵션이다. 명령에 거는 "조건 스티커"라고 생각하면 된다.

은행 앱 기간 조회 + 실시간 잔액이랑 똑같다

은행 앱에서 "이 날짜부터 이 날짜까지" 거래만 골라 보는 게 기간 조회다. 잔고가 실시간으로 줄어드는 걸 지켜보는 게 라이브 모니터링이다.

기간 골라 보기

--since와 --until을 붙여서 기간을 고른다.

bunx ccusage daily --since 20250722 --until 20250723

날짜는 붙여서 8자리로 쓴다. 20250722는 2025년 07월 22일이다. 구분자(-나 /) 없이 연4 + 월2 + 일2로 쓴다.

이렇게 하면 그 기간 표만 나온다.

Date       Models              Input    Output    Cost (USD)
2025-07-22 - opus-4            18,395   168,396   $43.82
             - sonnet-4
2025-07-23 - opus-4            52,448   96,218    $35.72
             - sonnet-4
Total                          70,843   264,614   $79.54

(위 숫자는 원서/노트의 예시 값이다.)

이 기간 필터는 daily만 되는 게 아니다. monthly, session, blocks 어디에든 똑같이 붙일 수 있다.

실시간으로 지켜보기 (라이브 모니터링)

라이브 모니터링을 켜면 지금 블록 상태가 1초마다 갱신된다.

┌──────────────────────────────────────────────────┐
│        CLAUDE CODE - LIVE TOKEN USAGE MONITOR    │
│                                                  │
│  SESSION  [########........]  25.1%              │
│    Started: 11:00:00 AM  Remaining: 3h (04:00 PM)│
│                                                  │
│  USAGE  [##..............]  (16 tokens)          │
│    Tokens: 16 (Burn Rate: N/A)       Cost: $0.23 │
│                                                  │
│  Models: sonnet-4                                │
│    Refreshing every 1s   Press Ctrl+C to stop    │
└──────────────────────────────────────────────────┘

화면 항목을 보자.

용어: Burn Rate란 토큰이 닳는 속도다. 자동차 연비 게이지처럼, 지금 얼마나 빠르게 토큰을 쓰는지 보여준다. 거의 안 쓰면 N/A(측정 안 됨)로 나온다.

화면을 끄려면 Ctrl+C를 누른다. 안 누르면 계속 1초마다 갱신하며 돈다.

이럴 때 이렇게

"지금 블록이 얼마나 남았고, 토큰이 빨리 닳는지 실시간으로 보고 싶어." → 라이브 모니터링을 켜면 남은 시간과 소비 속도가 1초마다 갱신된다. 다 봤으면 Ctrl+C로 끈다.

짚고 가기

• 기간은 --since YYYYMMDD --until YYYYMMDD 형식으로 고른다.
• 이 필터는 daily, monthly, session, blocks 모두에 붙일 수 있다.
• 라이브 모니터링은 1초마다 갱신되고, Ctrl+C로 끈다.

25-8 ccusage를 MCP 서버로 붙이기

이런 적 있죠?

지금까지는 사용량을 보려면 따로 터미널 창을 열어 ccusage를 쳐야 했다. 작업하다 매번 다른 창으로 넘어가는 게 번거롭다.

"클로드 코드 안에서 그냥 물어보면 안 되나? '오늘 얼마 썼어?' 하고."

된다. ccusage를 MCP 서버로 붙이면 된다.

용어: MCP란 클로드 코드가 외부 도구와 이어지는 표준 연결 방식이다. 멀티탭 콘센트라고 생각하면 된다. ccusage를 그 콘센트에 꽂으면, 클로드 코드가 ccusage를 직접 쓸 수 있다.

용어: MCP 서버란 그 콘센트에 꽂는 도구 쪽이다. ccusage를 MCP 서버로 켜두면, 클로드 코드가 필요할 때 불러 쓴다.

대시보드를 앱 안에 넣기랑 똑같다

지금까지는 사용량 대시보드를 따로 들고 다닌 셈이다 (별도 터미널 창). MCP 연동은 그 대시보드를 클로드 코드 앱 안에 직접 넣는 것이다. 앱을 안 떠나고 바로 확인한다.

1단계 — ccusage를 MCP 서버로 켜기

터미널에서 이 명령을 친다.

bunx ccusage mcp

커서가 멈춘 채로 가만히 있으면 정상이다. MCP 서버가 잘 켜져서 대기 중이라는 뜻이다.

2단계 — .mcp.json에 등록하기

프로젝트 폴더 맨 위(루트)에 있는 .mcp.json 파일에 ccusage를 적어둔다.

용어: .mcp.json이란 "이 프로젝트에서 어떤 MCP 도구를 쓸지" 적어두는 설정 파일이다. 멀티탭에 뭘 꽂을지 적어둔 메모라고 생각하면 된다.

{
  "mcpServers": {
    "ccusage": {
      "command": "bunx",
      "args": ["ccusage", "mcp"]
    }
  }
}

이렇게 적어두면 클로드 코드가 ccusage를 자동으로 불러 쓸 수 있다.

등록하고 나면 — 말로 물어보기

이제 클로드 코드 대화창에서 그냥 물어보면 된다.

"오늘 토큰 얼마나 썼어?" → ccusage가 daily 데이터를 찾아서 답해준다.

"이번 달 비용 얼마야?" → ccusage가 monthly 데이터를 찾아서 답해준다.

터미널을 따로 안 열어도, 대화하다가 바로 물어볼 수 있다.

잘못된 예 vs 올바른 예

잘못된 예. bunx ccusage mcp를 쳤는데 커서가 멈췄다. "멈췄네? 고장 났나? Ctrl+C로 꺼야지." → 멈춘 게 정상이다. 끄면 서버가 꺼진다.

올바른 예. "커서가 멈춘 채 대기하는 게 서버가 켜진 상태구나. 이대로 두자." → 맞다. 멈춤 = 정상 대기다.

짚고 가기

• bunx ccusage mcp로 ccusage를 MCP 서버로 켤 수 있다.
• .mcp.json에 등록하면 프로젝트에서 자동 연동된다.
• 연동 후에는 클로드 코드 대화 중에 사용량을 말로 물어볼 수 있다.

연습문제

문제 1 (기본)

ccusage의 네 가지 통계 명령(daily, monthly, session, blocks)을 각각 한 문장으로 설명해보자.

문제 2 (중급)

2025년 8월 1일부터 8월 15일까지의 일별 사용량만 보는 명령을 써보자. 그리고 날짜를 어떤 형식으로 쓰는지 설명해보자.

bunx ccusage daily --since 20250801 --until 20250815

문제 3 (심화)

워크트리로 새 폴더를 만들면 왜 새로운 세션으로 잡히는지 설명하고, 이걸 이용해 작업별 비용을 따로 보는 방법을 말해보자.

한눈에 정리

ccusage 명령 비교

bun 설치 명령 비교

ccusage 있을 때 vs 없을 때

참고 자료

ccusage, bun은 서드파티 도구다. 설치법과 화면은 바뀔 수 있으니, 정확한 최신 내용은 위 공식 저장소에서 확인하자.

다음 장 예고

다음 장에서는 또 다른 외부 도구를 소개한다. 지금 몰라도 이 장을 이해하는 데는 전혀 지장 없다.